/*
 
 TopMind jLynx "jLynx JDBC Framework"
 Copyright (c) 2004-2007. TopMind Systems Inc.
 All rights reserved.
 
 This file is part of TopMind jLynx.
 
 TopMind jLynx is free software; you can redistribute it and/or modify
 it under the terms of the License. See website for License.
 
 */
package net.sf.jlynx;

import java.io.Serializable;
import java.sql.SQLException;
import java.util.List;

/**
 * This interface defines essential methods needed to persist and retrieve POJOs
 * from relational databases systems (RDBMS); to create an instance use the
 * <code>RelationalFactory</code> class. As of v1.0 R3,
 * <code>java.util.Map</code> persistence is supported along with POJO
 * persistence.<br>
 * <br>
 * The API currently supports / has been tested on the following databases:
 * 
 * <ul>
 * <li>IBM DB2/UDB
 * <li>Microsoft SQL Server 2000
 * <li>Oracle 9i,10g
 * <li>MySQL
 * <li>HSQL
 * </ul>
 * 
 * <p>
 * jLynx Framework<br>
 * $Id: Relational.java 99 2007-06-21 02:51:13Z gritc11 $
 * </p>
 * 
 */
public interface Relational extends Serializable {

	/**
	 * Commit database transaction; by default jLynx will auto-commit.
	 * 
	 * @since v1.0
	 */
	void commit();

	/**
	 * Deletes 1 row from a database. Usage:<br>
	 * <br>
	 * <code>RelationalFactory.getInstance(bean).delete();</code>
	 * </p>
	 * 
	 * @return boolean - Was the record deleted? Yes or No
	 * @throws java.sql.SQLException
	 * @since v1.0
	 */
	boolean delete() throws java.sql.SQLException;

	/**
	 * 
	 * <p>
	 * Execute named query from jlynx.xml.
	 * </p>
	 * <p>
	 * Usage example:
	 * </p>
	 * <p>
	 * In jlynx.xml...
	 * <code>&lt;query name='<span class='bolder'>qryName</span>'&gt;
	 * UPDATE sometable SET somefield=?
	 * &lt;/query&gt;</code>
	 * </p>
	 * <p>
	 * <code>Relational r = RelationalFactory.getInstance();<br>
	 * boolean result = r.executeNamedQuery("<span class='bolder'>qryName</span>", new Object[]{new Integer(1)});
	 * </code>
	 * </p>
	 * 
	 * @return boolean
	 * @see java.sql.PreparedStatement#execute()
	 * @param namedQuery
	 *            Query in jlynx.xml
	 * @throws SQLException
	 * @since v1.3 - replaced Relational#execute()
	 * 
	 */
	public boolean executeNamedQuery(String namedQuery, Object[] params)
			throws SQLException;

	/**
	 * <p>
	 * Returns a list of objects from the database.
	 * </p>
	 * <p>
	 * Usage example:
	 * </p>
	 * <p>
	 * In jlynx.xml...
	 * <code>&lt;query name='<span class='bolder'>qryName</span>'&gt;
	 * SELECT * FROM sometable WHERE somefield=?
	 * &lt;/query&gt;</code>
	 * </p>
	 * <p>
	 * <code>Relational r = RelationalFactory.getInstance();<br>
	 * List result = r.getResultList("<span class='bolder'>qryName</span>", new Object[]{"T"});
	 * </code>
	 * </p>
	 * 
	 * @return List
	 * @see java.sql.PreparedStatement#executeQuery()
	 * @param namedQuery
	 *            query in jlynx.xml
	 * @param params
	 * @throws SQLException
	 * @since v1.3 - replaced Relational#getPreparedStatement() and
	 *        Relational#executeQuery()
	 */
	public List getResultList(String namedQuery, Object[] params)
			throws SQLException;

	/**
	 * As above (Relational#getResultList) except output is Xml.
	 * 
	 * @return String List as XML
	 * @param namedQuery
	 *            Query from jlynx.xml or SQL Statement
	 * @param params
	 *            SQL statement parameters (see java.sql.PreparedStatement)
	 * @param elementName
	 *            as in <span class='bolder'>&lt;Element /&gt;</span> - if null
	 *            elementName = object name
	 * @since v1.3.4
	 * @throws SQLException
	 */
	public String getResultListXml(String namedQuery, Object[] params,
			String elementName) throws SQLException;

	/**
	 * Inserts 1 row into a database. Usage:<br>
	 * <br>
	 * <code>Relational r =  RelationalFactory.getInstance(bean);<br>
	 * r.insert();</code>
	 * </p>
	 * 
	 * @return int No. of rows inserted -- or -- ID of record inserted (MySQL
	 *         and Microsoft SQL Server only)
	 * 
	 * @throws java.sql.SQLException
	 * 
	 * @since v1.0
	 */
	int insert() throws java.sql.SQLException;

	/**
	 * Rollback database transaction if autoCommit is off; by default, jLynx
	 * commits all database transactions.
	 * 
	 * @since v1.0
	 */
	void rollback();

	/**
	 * Saves POJO to database; equivalant to <code>update()</code> if record
	 * exists or insert() if record does not exist. POJO is then updated with
	 * current database values.
	 * 
	 * @return int
	 * @throws SQLException
	 */
	int save() throws SQLException;

	/**
	 * Whether nulls should be preserved in UPDATE and INSERT statements; by
	 * default NULL property values are removed from the statement. Empty
	 * Strings are treated as NULLs if set to true.
	 * 
	 * @param keepNullsInQuery
	 *            true (nulls are preserved) or false (default - nulls removed
	 *            from SQL queries)
	 * 
	 * @since v1.0
	 */
	void saveNulls(boolean keepNullsInQuery);

	/**
	 * Select the associated record from the database and populate the POJO's
	 * values.
	 * 
	 * Usage:<br>
	 * <br>
	 * <code>Relational r = RelationalFactory.getInstance(bean);<br>
	 * r.select();
	 * </code>
	 * </p>
	 * 
	 * @return boolean if records exists returns <code>true</code>
	 * @throws java.sql.SQLException
	 * @since v1.0
	 */
	boolean select() throws java.sql.SQLException;

	/**
	 * Set the connection auto_commit property; by default auto_commit is on
	 * (true).
	 * 
	 * @param boolean
	 * @return Relational
	 * @since v1.0
	 */
	Relational setAutoCommit(boolean b);

	/**
	 * Set the entity to be used for CRUD operations when XML mapping is not
	 * present.
	 * 
	 * @param entity
	 * @return Relational
	 * @since v1.0 R3
	 */
	Relational setEntity(String entity);

	/**
	 * Set the connection instead of using connection configuration in
	 * jlynx.xml.
	 * 
	 * @param conn
	 * @return Relational
	 * @throws SQLException
	 * @since v1.3.8
	 */
	Relational setConnection(java.sql.Connection conn) throws SQLException;

	/**
	 * Set the underlying Java object, typically a POJO or Map.
	 * 
	 * @param bean
	 * @return Relational
	 * @since v1.0 R3
	 */
	Relational setObject(Object bean);

	/**
	 * Convert the underlying Pojo or Map to a JSON String.
	 * 
	 * @since v1.3.6
	 * @return String
	 * 
	 */
	String toJSON();

	/**
	 * Convert the underlying Pojo or Map to an XML String.
	 * 
	 * @since v1.3.3
	 * @return String
	 * 
	 */
	String toXml();

	/**
	 * Convert the underlying Pojo or Map to an XML String.
	 * 
	 * @since v1.3.3
	 * @return String
	 * @param elementName
	 *            if null defaults to object name
	 * 
	 */
	String toXml(String elementName);

	/**
	 * <p>
	 * Update 1 row in the database.
	 * </p>
	 * 
	 * <p>
	 * Usage: create a Relational instance, like this:<br>
	 * <br>
	 * <code>Relational r = RelationalFactory.getInstance(bean);<br>
	 * r.update();</code>
	 * </p>
	 * 
	 * @return int - No. of rows affected by the update (should return 1)
	 * @throws java.sql.SQLException
	 * @since v1.0
	 */
	int update() throws java.sql.SQLException;

}
